{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-aria/textfield';
import {HeaderInfo, FunctionAPI, TypeContext, InterfaceType, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-aria/textfield/package.json';
import Anatomy from './anatomy.svg';


---
category: Forms
keywords: [textfield, textbox, input, label, aria]
---

# useTextField

<PageDescription>{docs.exports.useTextField.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['useTextField']}
  sourceData={[
    {type: 'W3C', url: 'https://www.w3.org/TR/wai-aria-1.2/#textbox'}
  ]} />

## API

<FunctionAPI function={docs.exports.useTextField} links={docs.links} />

## Features

Text fields can be built with [&lt;input&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
or [&lt;textarea&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)
and [&lt;label&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label) elements,
but you must manually ensure that they are semantically connected via ids for accessibility.
`useTextField` helps automate this, and handle other accessibility features while
allowing for custom styling.

* Built with a native `<input>` or `<textarea>` element
* Visual and ARIA labeling support
* Change, clipboard, composition, selection, and input event support
* Support for native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and server-side validation errors
* Support for description and error message help text linked to the input via ARIA

## Anatomy

<Anatomy />

Text fields consist of an input element and a label. `useTextField` automatically manages
the relationship between the two elements using the `for` attribute on the `<label>` element
and the `aria-labelledby` attribute on the `<input>` element.

`useTextField` also supports optional description and error message elements, which can be used
to provide more context about the field, and any validation messages. These are linked with the
input via the `aria-describedby` attribute.

`useTextField` returns props that you should spread onto the appropriate element:

<TypeContext.Provider value={docs.links}>
  <InterfaceType properties={docs.links[docs.exports.useTextField.return.base?.id ?? docs.exports.useTextField.return.id].properties} />
</TypeContext.Provider>

If there is no visual label, an `aria-label` or `aria-labelledby` prop must be passed instead
to identify the element to screen readers.

## Example

```tsx example export=true
import type {AriaTextFieldProps} from '@react-aria/textfield';
import {useTextField} from '@react-aria/textfield';

function TextField(props: AriaTextFieldProps) {
  let {label} = props;
  let ref = React.useRef(null);
  let {labelProps, inputProps, descriptionProps, errorMessageProps, isInvalid, validationErrors} = useTextField(props, ref);

  return (
    <div style={{display: 'flex', flexDirection: 'column', width: 200}}>
      <label {...labelProps}>{label}</label>
      <input {...inputProps} ref={ref} />
      {props.description && <div {...descriptionProps} style={{fontSize: 12}}>{props.description}</div>}
      {isInvalid && <div {...errorMessageProps} style={{color: 'red', fontSize: 12}}>{validationErrors.join(' ')}</div>}
    </div>
  );
}

<TextField label="Email" />
```

### Text area

`useTextField` also supports multi-line text entry with the `<textarea>` element via the `inputElementType` prop.

```tsx example
import type {AriaTextFieldProps} from '@react-aria/textfield';
import {useTextField} from '@react-aria/textfield';

function TextArea(props: AriaTextFieldProps<HTMLTextAreaElement>) {
  let {label} = props;
  let ref = React.useRef(null);
  let {labelProps, inputProps} = useTextField({...props, inputElementType: 'textarea'}, ref);

  return (
    <div style={{display: 'flex', flexDirection: 'column', width: 200}}>
      <label {...labelProps}>{label}</label>
      <textarea {...inputProps} ref={ref} />
    </div>
  );
}

<TextArea label="Description" />
```

## Usage

The following examples show how to use the `TextField` component created in the above example.

### Default value

A TextField's `value` is empty by default, but an initial, uncontrolled, value can be provided using the `defaultValue` prop.

```tsx example
<TextField
  label="Email"
  defaultValue="me@email.com" />
```

### Controlled value

The `value` prop can be used to make the value controlled. The `onChange` event is fired when the user edits the text, and receives the new value.

```tsx example
function Example() {
  let [text, setText] = React.useState('');

  return (
    <>
      <TextField label="Your text" onChange={setText} />
      <p>Mirrored text: {text}</p>
    </>
  );
}
```

### Description

The `description` prop can be used to associate additional help text with a text field.

```tsx example
<TextField
  label="Email"
  description="Enter an email for us to contact you about your order." />
```

### Validation

useTextField supports HTML constraint validation props such as `isRequired`, `type="email"`, `minLength`, and `pattern`, as well as custom validation functions, realtime validation, and server-side validation. It can also be integrated with other form libraries. See the [Forms](../forms) guide to learn more.

When a TextField has the `validationBehavior="native"` prop, validation errors block form submission. To display validation errors, use the `validationErrors` and `errorMessageProps` returned by `useTextField`. This allows you to render error messages from all of the above sources with consistent custom styles.

```tsx example
<form>
  <TextField
    label="Email"
    name="email"
    /*- begin highlight -*/
    type="email"
    isRequired
    validationBehavior="native"
    /*- end highlight -*/
  />
  <input type="submit" style={{marginTop: 8}} />
</form>
```

### Disabled

A TextField can be disabled using the `isDisabled` prop.

```tsx example
<TextField label="Email" isDisabled />
```

### Read only

The `isReadOnly` boolean prop makes the TextField's text content immutable. Unlike `isDisabled`, the TextField remains focusable
and the contents can still be copied. See [the MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/readonly) for more information.

```tsx example
<TextField label="Email" defaultValue="abc@adobe.com" isReadOnly />
```

### Required

A TextField can be marked as required using the `isRequired` prop. This is exposed to assistive technologies by React Aria. It's your responsibility to add additional visual styling if needed.

```tsx example
<TextField label="Email" isRequired />
```

### HTML forms

TextField supports the `name` prop for integration with HTML forms. In addition, attributes such as `type`, `pattern`, `inputMode`, and others are passed through to the underlying `<input>` element.

```tsx example
<TextField label="Email" name="email" type="email" />
```

## Internationalization

### RTL

In right-to-left languages, text fields should be mirrored. The label should be right aligned,
along with the text in the text field. Ensure that your CSS accounts for this.
